home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 22
/
Cream of the Crop 22.iso
/
program
/
snpd9611.zip
/
ZDATE.MAN
< prev
Wrap
Text File
|
1996-11-24
|
48KB
|
1,074 lines
+++Date last modified: 26-Oct-1996
ZDATE - THE COMPLETE DATE MANIPULATION SOLUTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The zDate class (all code, manuals and examples) is
Copyright (c) 1995, 1996 Branislav L. Slantchev
(CompuServe: 73023,262)
THIS VERSION IS EXPLICITLY DONATED BY THE AUTHOR TO THE SNIPPETS
COLLECTION MAINTAINED BY BOB STOUT. YOU ARE ALLOWED TO USE THE
CODE FOR ANY PURPOSE (INCLUDING COMMERCIAL) FREE OF CHARGE AS
LONG AS YOU ACKNOWLEDGE IT. YOU ARE NOT ALLOWED TO REMOVE THE
COPYRIGHT NOTICES FROM THE CODE. YOU ARE FREE TO MAKE ANY
MODIFICATIONS NECESSARY TO SUIT YOUR NEEDS. I WILL APPRECIATE IF
YOU NOTIFY ME OF THESE CHANGES BUT THIS IS NOT A REQUIREMENT.
THERE ARE NO WARRANTIES, EITHER EXPRESS OR IMPLIED ABOUT THE
FITNESS OF THIS PRODUCT FOR ANY PARTICULAR PURPOSE. USE AT YOUR
OWN RISK. THE AUTHOR WILL BE IN NO WAY LIABLE FOR ANY USE, MISUSE
OR INABILITY TO USE OF THIS PRODUCT, AS WELL AS ANY LOSSES THAT
MIGHT HAVE OCCURRED AS RESULT OF THESE.
The zDate class provides your C++ programs with one of the most useful and
easy to use date classes I have seen. It has been developed over a period of
almost two years, with the functionality being refined to the point that the
class interface is unobtrusive and intuitive. You won't have to worry about
hidden assumptions, or side effects or oddly-named member functions.
Everything is in plain sight. Having said that, let's look at some class
specifics.
The zDate class is not meant to be used as a base class. You can, of course,
but there's little point in doing it. There are no date formatting functions.
I felt that these are fairly easy to find and the ANSI C library provides a
very useful implementation in its strftime() function. There was simply no
need to re-invent the wheel. The class, however, provides all the
functionality you might need. Simple operators like comparison and assignment
make the class as straightforward as can be. All the enumerated constants are
encapsulated within the class to avoid namespace pollution. This class was
written with the century roll-over in mind. It will work just fine after the
year 2000 unlike many other implementations.
I should note here that the day numbering used internally (and retrievable
via the DayNumber() function) is NOT the true Julian day scheme. This one
begins at 1 A.D. unlike the Julian day numbers which go back 4000 years B.C.
Effectively, this means that you cannot have dates which go into negative
years, but I have yet to see this as a limitation worthy of a class re-
design.
The class follows the general PB-Lib coding standards. For a complete
reference, read the file Standard.Doc available with the library release.
It should suffice to note that all member functions use mixed-case naming,
with the first letters of each word capitalized. Functions that do not
modify the class internals are declared as const. Functions that can be
used without actually instantiating an object of the class are declared
static. These can be used with the simple scope resolution operator without
an object pointer. What follows is a complete class reference for all public
data members and methods. Note that private and protected members and methods
are not documented here. They are, however, fully explained with code
comments.
ZDATE::MONTH
--------------------------------------------------------------------------
Synopsis Enumeration type for the months of the year.
Syntax enum month { jan=1, feb, mar, apr, may, jun,
jul, aug, sep, oct, nov, dec };
Remarks Use this enumeration to interpret the return values of
various member functions. You should use the scope
resolution operator to access them outside the class.
Return n/a
See also zDate::week_day; zDate::moon_phase
Example zDate::month myMonth = zDate::jul;
if( zDate::aug == myMonth ) cout << "This can't be.";
ZDATE::WEEK_DAY
--------------------------------------------------------------------------
Synopsis Enumeration type for the different days of the week.
Syntax enum week_day { mon=1, tue, wed, thu, fri, sat, sun };
Remarks Use these enumerated constants to access the various day of
week return values of functions. You must use the scope
resolution operator to access them.
Return n/a
See also zDate::month; zDate::moon_phase
Example zDate::week_day wday = zDate::sun;
switch( wday ){
case zDate::sat:
case zDate::sun:
cout << "Oh, weekend! I love those" << endl;
break;
default: cout << "Another boring day!" << endl;
}
ZDATE::MOON_PHASE
--------------------------------------------------------------------------
Synopsis Enumeration constants to access the return value of the
MoonPhase routines.
Syntax enum moon_phase{ new_moon, waxing_crescent, first_quarter,
waxing_gibbous, full_moon, waning_gibbous,
third_quarter, waning_crescent };
Remarks Use these enumerated constants to interpret the return value
of the MoonPhase() member function. You should use the scope
resolution operator to access them.
Return n/a
See also zDate::MoonPhase; zDate::month; zDate::week_day
Example zDate::moon_phase phase = zDate::MoonPhase(zDate::Today());
switch( phase ){
case zDate::full_moon:
cout << "Grrrrr! The Werewolves are out!";
break;
default: cout << "Nothing yet!" << endl;
}
ZDATE::ZDATE
--------------------------------------------------------------------------
Synopsis Various constructors to initialize the date objects.
Syntax zDate();
zDate(month aMonth, int aDay, int aYear);
zDate(int dayOfYear, int aYear);
zDate(const zDate &aDate);
zDate(ulong nDayNumber);
zDate(const struct tm *tmDate);
Remarks These constructors are used to initialize the date object in
various ways. The parameter names are self-explanatory.
Things you should know are that none of these constructors
will check the validity of the data being passed to it. You
must verify that all parameters are correct or the results
will be unpredictable. Years are specified in full (i.e. for
1996, you must pass 1996 as the aYear parameter, not 96 or
anything else). Years can go back to 1 A.D. You cannot use
negative years. The earliest date that is valid for the zDate
class is January 1, 0001. The 'dayOfYear' parameter must be
the number of the day for the 'aYear', starting with January 1
as day number 1. The 'nDayNumber' parameter is NOT the true
Julian day number of the day (these start some 4,000 years BC).
Rather, it's the day number with base of January 1, 0001 as
the 1st day. For the last constructor, the 'tmDate' parameter
must be correctly initialized as per its specifications (see
your compiler manual). With this format, the year is an
offset from 1900 (that is, 1996 is 96 and 2012 is 112). Also,
the month numbering scheme is different. These are all taken
care of in the zDate constructor itself. Finally, the copy
constructor will initialize the current zDate object with the
value of another one.
Return n/a
See also zDate::Today(); zDate::EndDST(); zDate::BeginDST()
Example // here are examples of all possible ways of initialization
zDate date1; // January 1, 0001
zDate date2(zDate::jul, 16, 1973); // July 16, 1973
zDate date3(15, 1995); // January 15, 1995
zDate date4(date2); // same as date2
zDate date5(728945L); // October 11, 1996
time_t secs = time(0); // current time/date
zDate date6( localtime(&secs) ); // (use struct tm*)
zDate date7(zDate::Today()); // current date
ZDATE::ADDMONTHS
--------------------------------------------------------------------------
Synopsis Adds or subtracts months from the date object.
Syntax zDate AddMonths(int nMonths) const;
Remarks This member function will add or subtract (if 'nMonths' is
negative) the number of months to the current date object and
will return another zDate object with the new values. It does
not modify the current object. This will adjust the number of
years if necessary. Note that month arithmetic is fairly
straightforward as only the month will be changed regardless
of the days in each month. However, this may cause some
invalid dates (such as July 31 minus 5 months is February 31,
which is clearly invalid). The function will adjust the day
of the month in that case according to the following rules:
if adding months, the month will roll over into the next one
(causing a year increase, if necessary) and the new day number
will be the overflow (i.e. April 31 will become May 1). If
subtracting, the overflow is subtracted from the current day
number (i.e. in the example with February, the new day will
be 27 or 26, depending on whether the year is leap or not).
Care must be taken when subtracting months not to cause the
year to become less that 1 A.D.
Return A zDate object with the new date value.
See also zDate::AddYears(); zDate::AddWeeks(); zDate::operator+();
Example zDate ind(zDate::jul, 4, 1776);
assert(ind.AddMonths(2400)==zDate(zDate::jul,4,1996));
ZDATE::ADDWEEKS
--------------------------------------------------------------------------
Synopsis Adds or subtracts a number of weeks from the date object.
Syntax zDate AddWeeks(int nWeeks) const;
Remarks This member function will add or subtract (if 'nWeeks' is
negative) the number of weeks from the current date object
and will return a new zDate object with the resulting value.
It does not modify the calling object. There are no fancy
calculations with this function, it simply uses weeks as
spans of 7 days and actually adds/subtracts days. This will
modify the year and the month, as well as the day as necessary.
Care must be taken that the year does not become less than
1 A.D.
Return A zDate object with the new date value.
See also zDate::AddYears(); zDate::AddMonths(); zDate::operator+();
Example zDate date(zDate::oct, 11, 1996);
assert(date.AddWeeks(-1) == zDate(zDate::oct,4,1996));
ZDATE::ADDYEARS
--------------------------------------------------------------------------
Synopsis Adds or subtracts a number of years from a date.
Syntax zDate AddYears(int nYears) const;
Remarks This member function will add or subtract (if 'nYears' is
negative) a number of years to the current date object and
will return a new zDate with the resulting value. The calling
object is not modified by this function. Note that when
manipulating years, a date could become invalidated (such as
adding 1 to a leap year will cause February 29 to be an
invalid date). This routine takes that into account and will
adjust itself accordingly (in the example above, the new date
will be March 1). Care must be taken that years do not fall
below 1 A.D.
Return A zDate object with the new date.
See also zDate::AddWeeks(); zDate::AddMonths(); zDate::operator+();
Example zDate date(zDate::feb, 29, 1996);
assert(date.AddYears(-2) == zDate(zDate::mar,1,1994));
ZDATE::AGE
--------------------------------------------------------------------------
Synopsis Returns the age of someone with a specific birthrate
(for current date object).
Syntax int Age(const zDate &BirthDay) const;
Remarks This routine calculates the age of a person with a birthday
date of 'BirthDay'. This function does not modify the calling
object. Care must be taken that the calling object is greater
than BirthDay (i.e. that the person has already been born).
Return The age (in years) of the person.
See also zDate::operator-()
Example zDate brani(zDate::jul, 16, 1973);
cout << "I am " << Today().Age(brani) << " years old";
ZDATE::BEGINDST
--------------------------------------------------------------------------
Synopsis Calculates the beginning date of the Daylight Savings Time.
Syntax zDate BeginDST() const;
static zDate BeginDST(int aYear);
Remarks There are two version of this function. The first one returns
the date of the beginning of DST for the year of the current
date object. The second one is more generic as it returns the
start of DST for any year. These routine do not modify
anything, they simply return a zDate object with the date
when the DST comes into effect. By default, the routines will
use the USA standard for DST calculations. In the US, DST
begins at 2:00am on the first Sunday of April and ends at
2:00am on the last Sunday of October. You can modify these
rules by using the SetBeginDST() and SetEndDST() member
functions.
Return The date when DST will come into effect.
See also zDate::EndDST(); zDate::IsDST(); zDate::SetBeginDST()
Example assert(zDate::BeginDST(1996)==zDate(zDate::apr,7,1996))
ZDATE::DAY
--------------------------------------------------------------------------
Synopsis Returns the day of month of the current date object.
Syntax int Day() const;
Remarks This routine return the current day of the month. Days start
from 1 and can go up to 31, depending on the current day.
Note that there are no days between October 4 and October 15,
1582 (this is when Pope Gregor XIII canceled them).
Return The day of the month.
See also zDate::Month(); zDate::Year(); zDate::DayOfWeek();
Example cout << "Today is the " << zDate::Today().Day()
<< "th day of the month";
ZDATE::DAYNUMBER
--------------------------------------------------------------------------
Synopsis Returns the day number (from January 1, 1) for the object.
Syntax ulong DayNumber() const;
Remarks This returns the day number of the date object. Day numbering
begins with January 1, 0001 A.D. being day 1 and so on. As
such, these day numbers are not Julian dates (which begin
several thousand years B.C.). Leap years are taken into
account as well as the Gregorian reform (with the standard
date of October 4, 1582)
Return The day number (unsigned long integer).
See also zDate::zDate(ulong nDayNumber);
Example cout << "Today is the " << zDate::Today().DayNumber()
<< "th day of the year.";
ZDATE::DAYOFWEEK
--------------------------------------------------------------------------
Synopsis Returns the day of the week for the date object.
Syntax week_day DayOfWeek() const;
Remarks This returns the day of the week for the current date object.
You must use the week_day enumeration to interpret the return
value of this function. When trying to access the week_day
constants, be sure to use the scope resolution operator.
Return The day of the week.
See also zDate::week_day;
Example assert(zDate::sat == zDate(zDate::oct,5,1996).DayOfWeek());
ZDATE::DAYOFYEAR
--------------------------------------------------------------------------
Synopsis Returns the day of the year from January 1.
Syntax int DayOfYear() const;
Remarks This member function returns the day of the year for the
current object. The day numbering starts from January 1 for
the same year being the first day. The current day number
will depend on whether the year is leap or not too. The range
of possible values is 1..366 (or 365 for non-leap years),
with the upper limit being December 31.
Return The day number.
See also zDate::DayOfWeek(); zDate::DayNumber();
Example assert(366 == zDate(zDate::dec,31,2000).DayOfYear());
ZDATE::DAYSINMONTH
--------------------------------------------------------------------------
Synopsis Returns the number of days for a specific month in a year.
Syntax int DaysInMonth() const;
static int DaysInMonth(month aMonth, int aYear);
Remarks These two versions of the function will return the number of
days for a specific month. The first version will return the
number of days in the month of the date object that called it;
while the second version can be used without an actual zDate
object and returns the number of days for a month of a year
you specify. Note that October 1582 had only 21 days as a
result of the reform of Pope Gregor XIII.
Return The number of days in a month.
See also zDate::DaysInYear(); zDate::IsLeapYear();
Example assert( 28 == zDate::DaysInMonth(zDate::feb, 1995) );
ZDATE::DAYSINYEAR
--------------------------------------------------------------------------
Synopsis Returns the number of days in a specific year.
Syntax int DaysInYear() const;
static int DaysInYear(int aYear);
Remarks The first version of this routine returns the number of days
in the year of the current date object. The second version
can be used without instantiating an actual object and returns
the number of days in any year. There are two possible values
365 and 366 depending on whether the year is leap or not
(except for 1582 which lost 10 days). These functions do not
modify any objects.
Return The number of days in a year.
See also zDate::DaysInMonth(); zDate::IsLeapYear();
Example assert( 366 == zDate::DaysInYear(1996) );
ZDATE::EASTER
--------------------------------------------------------------------------
Synopsis Return the date of Easter for any given year.
Syntax zDate Easter() const;
static zDate Easter(int year);
Remarks This routine returns the date for Easter for any given year
(the second version) or for the year of the calling zDate
object. It uses some obscure algorithm to calculate the
ecclesiastical Easter (which is the same for all countries
regardless of where they are) and is different from the
astronomical date (which does not mean much anyway). Easter is
sometimes said to be the first Sunday that occurs after the
full moon that follows the vernal equinox (March 22). This
means the Easter can vary between March 22 and April 25. This
is an over-simplification as the Church does not actually use
astronomical observations of the Moon but rather, it has
constructed its own calendar of Easter days which it uses.
This function is a very presentable approximation. For more
information, read one of the Almanacs or visit the US Naval
Observatory. They have tons of nice information there,
including an even more obfuscated formula for calculating the
Easter date.
Return A zDate object with the Easter date.
See also zDate::MoonPhase(); zDate::DayOfWeek()
Example zDate Easter(zDate::apr, 7, 1996);
assert( Easter == zDate::Easter(1996) );
ZDATE::ENDDST
--------------------------------------------------------------------------
Synopsis Return the date when the Daylight Savings Time is ended.
Syntax zDate EndDST() const;
static zDate EndDST(int aYear);
Remarks This function is similar to BeginDST() except it returns the
date when the Daylight Savings Time stops being in effect.
The default uses the American convention of ending DST at
2:00am on the last Sunday of October. This behavior can be
modified to suit your specific locale.
Return A zDate object with the correct date.
See also zDate::IsDST(); zDate::SetEndDST(); zDate::BeginDST();
Example assert(zDate(zDate::oct,27,1996) == zDate::EndDST(1996));
ZDATE::ISDST
--------------------------------------------------------------------------
Synopsis Checks if a date falls in the Daylight Savings Time range.
Syntax Boolean IsDST() const;
static Boolean IsDST(const zDate &aDate);
Remarks This function checks if a date happens to be in the period
during which Daylight Savings Time is in effect. The default
uses the US convention which begins DST on the first Sunday of
April and ends it on the last Sunday of October. You can
modify the time span of the DST period with the SetBeginDST()
and SetEndDST() functions. The second version is more generic
and will check any date object (the first one is intended to
be called via an object to check itself).
Return True, if the date falls in the DST period range;
False, otherwise.
See also zDate::SetBeginDST(); zDate::SetEndDST)();
Example assert( zDate(zDate::jul, 16, 1996).IsDST() );
ZDATE::ISLEAPYEAR
--------------------------------------------------------------------------
Synopsis Checks if a specific year is leap.
Syntax Boolean IsLeapYear() const;
static Boolean IsLeapYear(int aYear);
Remarks This routine checks if a year is leap or not. Leap years are
defined as follows: before the Gregorian reform, any year
divisible by 4 is a leap year. After the reform, all years
divisible by 4 are leap years unless they are also divisible
by 100 and not divisible by 400 (that means that 1500 was not
a leap year but 1600 was). The second version can be called
without a zDate object to check any year.
Return True if the year is leap; False otherwise.
See also zDate::DayNumber();
Example assert(True == zDate::IsLeapYear(1600));
assert(False == zDate(zDate::jan,1,1500).IsLeapYear());
ZDATE::ISVALID
--------------------------------------------------------------------------
Synopsis Checks if a date is valid.
Syntax Boolean IsValid() const;
static Boolean IsValid(month Month, int Day, int Year);
Remarks Checks if all the fields of a particular date are valid. Note
that this function is not called within the class member
routines. They all assume they are dealing with valid dates.
It is your responsibility to ensure that. A valid date is any
date after January 1, 0001 (with the exception of the days
between October 4 and 15, 1582). Also checked are the day of
month (this has to be correct for the current month). Note
that you can use the second version without an actual zDate
object to check any date.
Return True if the date is valid, False otherwise.
See also n/a
Example assert( !zDate(zDate::feb, 31, 1996).IsValid );
ZDATE::MONTH
--------------------------------------------------------------------------
Synopsis Returns the month of the date object.
Syntax zDate::month Month() const;
Remarks This routine returns the month of the current date object.
The return value can be examined via the zDate::month
enumeration constants. You will need to use the scope
resolution operator to access those.
Return The month of the year.
See also zDate::Year(); zDate::Day();
Example switch( zDate::Today().Month() ){
case zDate::jul:
cout << "This is my month!";
break;
default:
cout << "Just another month";
break
}
ZDATE::MOONPHASE
--------------------------------------------------------------------------
Synopsis Determines the phase of the moon.
Syntax zDate::moon_phase MoonPhase() const;
static zDate::moon_phase MoonPhase(const zDate &aDate);
Remarks This routine determines the phase of the moon for a given
date. You need to use the supplied enumeration constants
'moon_phase' to interpret the result. The Moon moves through
8 phases on its way around the earth during the Moon cycle
which lasts about 30 days. Whenever the moon is between the
Earth and the Sun, we have a new moon (i.e. the Moon is not
visible in the sky). Then the Moon's visible surface starts
increasing and it moves through the waxing crescent, first
quarter, and waxing gibbous stages to the full moon position
(when the Earth is between the Moon and the Sun). From that
point on, the visible surface of the Moon decreases going
from waning gibbous, through the third quarter, and to a
waning crescent. Then the cycle repeats. You can use the
second version of the function to calculate the moon phase
for any date object.
Return The phase of the Moon.
See also zDate::moon_phase
Example zDate fullMoon(zDate::sep, 26, 1996);
assert( zDate::full_moon == fullMoon.MoonPhase() );
ZDATE::OPERATOR LONG
--------------------------------------------------------------------------
Synopsis Type cast of a zDate to a long integer, return the day number.
Syntax operator long() const;
Remarks This operator is useful for a type cast in situations where
you need a long number representation of the date. The same
effect can be achieved with the DayNumber() functions as the
results are identical. This may be a cleaner solution for some
situations (like passing the day number to a function which
expects a long, in which case you can specify the zDate
object as a parameter and the cast will be performed
automatically).
Return The day number from January 1, 0001 A.D.
See also zDate::DayNumber();
Example // this is a contrived example which forces the use
// of the zDate(ulong nDayNumber) constructor instead
// of the copy constructor. Generally, you don't want
// to do this, as the latter is a lot faster!
ZDate date( (long)zDate::Today() );
ZDATE::OPERATOR!=
--------------------------------------------------------------------------
Synopsis Tests two dates for inequality.
Syntax Boolean operator!=(const zDate &aDate) const;
Remarks This operator allows intuitive test for date inequality.
You can test if two dates are different using the regular
C++ notation.
Return True if dates are different, False if they are the same.
See also zDate::operator==();
Example zDate first(zDate::jul, 16, 1973);
zDate second = zDate::Today();
assert( first != second );
ZDATE::OPERATOR+
--------------------------------------------------------------------------
Synopsis Adds or subtracts a number of days from a date object.
Syntax zDate operator+(int nDays) const;
zDate operator+(long nDays) const;
Remarks This operator allows adding a number of days to a date object
or subtracting (if the 'nDays' parameter is negative) a
certain amount of days. Care should be taken that the
resulting year does not fall below 1 A.D. The current date
object is not modified, which is what is to be expected with
the standard C++ behavior.
Return A zDate object with the new date value.
See also zDate::operator+=(); zDate::operator++(0
Example zDate date1(zDate::oct, 3, 1996);
zDate date2 = date1 + 55;
assert( date2 == zDate(zDate::nov, 27, 1996) );
ZDATE::OPERATOR++
--------------------------------------------------------------------------
Synopsis Increments the date object by 1 day.
Syntax zDate operator++();
zDate operator++(int);
Remarks This is a simple increment operator which will increase the
current date object by 1 day. Note that both prefix and
postfix versions are supported. These behave in the standard
C++ way (i.e. the prefix version will cause the date object
to be modified and then the new value returned, while the
postfix version will cause the date object to be modified,
but its old value will be returned).
Return Prefix version returns incremented value of object;
Postfix version returns the value of the object before
the modification.
See also zDate::operator+=(); zDate::operatorù();
Example zDate date(zDate::jan, 1, 1996);
assert( zDate(zDate::jan, 1, 1996) == date++ );
assert( zDate(zDate::jan, 3, 1996) == ++date );
ZDATE::OPERATOR+=
--------------------------------------------------------------------------
Synopsis Adds a number of days to a date object and modifies it.
Syntax zDate& operator+=(int nDays);
zDate& operator+=(long nDays);
Remarks This operator behaves just like the regular C++ counterpart.
It will add the number of days in 'nDays' (which can be
negative too) to the current object and will modify it. It
also returns a reference to this object so chaining is
allowed.
Return A reference to the modified object.
See also zDate::operator+(); zDate::operator-=();
Example zDate date(zDate::oct, 4, 1996);
date += 217;
assert( date == zDate(zDate::sep, 5, 1997) );
ZDATE::OPERATOR-
--------------------------------------------------------------------------
Synopsis Subtracts days from a date object.
Finds difference between two dates.
Syntax long operator-(const zDate &aDate) const;
zDate operator-(int nDays) const;
zDate operator-(long nDays) const;
Remarks There are two distinct versions of this operator. The first
one is used to find the difference (in days) between two date
objects. The other version is used for subtracting a certain
number of days from a date object (or adding, of course, if
the 'nDays' parameter is negative). Care should be taken that
the resulting year is not smaller than 1 A.D.
Return The first version returns a long integer with the difference
(in days) between the two dates. This can be either negative
or positive or 0.
The second version returns a zDate object which contains the
resulting value.
See also zDate::operatorù(); zDate::operator-=();
Example zDate date1(zDate::jul, 4, 1776);
// this is the first version: difference in days
long days = zDate::Today() - date1;
cout << "There have been " << days
<< " days since Independence Day.";
// this is the second version: subtracting days
assert( date1 + days == zDate::Today() );
ZDATE::OPERATOR--
--------------------------------------------------------------------------
Synopsis Decrements the date object value by 1 day.
Syntax zDate operator--();
zDate operator--(int);
Remarks These are the decrement operators. They work exactly like
their C++ counterparts. Both the prefix and postfix versions
are supported. The prefix version will first modify the date
and then return the new value. The postfix will modify the
date and return the old value.
Return Prefix version returns new value of date;
Postfix version returns the old value of date.
See also zDate::operator-(); zDate::operator-=();
Example zDate date(zDate::oct, 5, 1996);
// test the postfix version (same value returned)
assert( zDate(zDate::oct, 5, 1996) == date-- );
// test the prefix version, new value returned
// note that date is already Oct 4, 1996 from above
assert( zDate(zDate::oct, 3, 1996) == --date );
ZDATE::OPERATOR-=
--------------------------------------------------------------------------
Synopsis Subtracts a number of days from an object and modifies it.
Syntax zDate& operator-=(int nDays);
zDate& operator-=(long nDays);
Remarks This operator subtracts 'nDays' days from the current object
and assigns the new value to it (or adds the days if the
'nDays' parameter is negative). Care must be taken so that
the resulting year is not smaller than 1 A.D. A reference to
the modified object is return to allow chaining.
Return Reference to the modified object.
See also zDate::operator+=(); zDate::operatorù();
Example zDate date(zDate::oct, 4, 1996);
date -= -217;
assert( date == zDate(zDate::sep, 5, 1997) );
ZDATE::OPERATOR<, OPERATOR<=, OPERATOR>, OPERATOR>=
--------------------------------------------------------------------------
Synopsis Operators to compare two dates.
Syntax Boolean operator> (const zDate &date2) const;
Boolean operator>=(const zDate &date2) const;
Boolean operator< (const zDate &date2) const;
Boolean operator<=(const zDate &date2) const;
Remarks These operators allow intuitive comparisons of two date
objects. They behave similarly to their C++ counterparts. A
date is considered "smaller" than another if it specifies an
earlier point in time (that is, July 16, 1973 is "smaller"
than July 16, 1996).
Return True if the comparison reflects the relative dates;
False otherwise.
See also zDate::operator==(); zDate::operator!=();
Example zDate date1 = zDate::Today();
assert( date1 > zDate(zDate::jan, 1, 1800) );
assert( date1 >= zDate::Today() );
assert( date1 < zDate(zDate::jan, 1, 2200) );
assert( date1 <= zDate::Today() );
ZDATE::OPERATOR=
--------------------------------------------------------------------------
Synopsis Operator that assigns one date object to another.
Syntax zDate& operator=(const zDate &aNewDate);
Remarks This operator allows assigning one date to another using the
usual C++ syntax. A reference to the modified object is
returned to allow proper chaining.
Return A reference to the current object with the new value.
See also zDate::zDate();
Example // date1 initialized via the copy constructor
zDate date1(zDate::Today());
// date2 initialized via the assignment operator
zDate date2 = zDate::Today();
assert( date1 == date2 );
ZDATE::OPERATOR==
--------------------------------------------------------------------------
Synopsis Tests two dates for equality.
Syntax Boolean operator==(const zDate &aDate) const;
Remarks Tests if the current day object contains the same date as
the 'aDate' parameter. This allows for intuitive test in the
usual C++ way.
Return True if the dates are the same; False otherwise.
See also zDate::operator!=();
Example zDate date1 = zDate::Today();
assert( date1 == zDate::Today() );
ZDATE::OPERATOR[]
--------------------------------------------------------------------------
Synopsis Return date information with array-like syntax.
Syntax char operator[](int index) const;
Remarks This arguably useful routine is of special interest to
ProBoard programmers. It can be used to get values in
DateType-compatible format (as used by ProBoard's SDK). The
only valid 'index' values are 0, 1, or 2. Anything else will
result in '-1' being returned. Index of 0 specifies that the
day is to be returned (1..31); index value of 1 specifies
that the month is to be returned (1..12); index value of 2
specifies that the year is to be returned in struct
tm-compatible format (i.e. 1996 is returned as 96).
Return Date information in DateType compatible format.
See also zDate::Day(); zDate::Month(); zDate::Year();
Example zDate date(zDate::jul, 16, 1973);
// this will print 16/7/73
cout << date[0] << "/" << date[1] << "/" << date[2];
ZDATE::SETBEGINDST
--------------------------------------------------------------------------
Synopsis Sets the beginning of Daylight Savings Time for the class.
Syntax static void SetBeginDST(month aMon, week_day aWeekDay);
Remarks Since the class defaults to the US convention of specifying
DST to begin on the first Sunday of April, it might be useful
to specify an alternative starting point. Note that the
'aWeekDay' is assumed to be the first one in the month. This
will set the internal values of the DST starting date.
Return Nothing.
See also zDate::SetEndDST(); zDate::IsDST(); zDate::BeginDST();
Example // set the DST to begin on first Monday of March
zDate::SetBeginDST(zDate::mar, zDate::mon);
ZDATE::SETENDDST
--------------------------------------------------------------------------
Synopsis Sets the ending of the Daylight Savings Time for the class.
Syntax static void SetEndDST(month aMonth, week_day aWeekDay);
Remarks Since the class defaults to the US convention of specifying
DST to end on the last Sunday of October, it might be useful
to specify an alternative ending point. Note that the
'aWeekDay' parameter is assumed to be the last occurrence of
this week day in the month. This will set the internal values
of the DST ending date.
Return Nothing.
See also zDate::SetBeginDST(); zDate::IsDST(); zDate::EndDST();
Example // set the DST to end on the last Monday of November
zDate::SetEndDST(zDate::nov, zDate::mon);
ZDATE::TODAY
--------------------------------------------------------------------------
Synopsis Returns a zDate object with today's date.
Syntax static zDate Today();
Remarks This is a very useful member function which returns a zDate
object that reflects the current system date. It can be used
without an actual instance of zDate (because it is static)
and can be passed to zDate constructors to set date objects
to the current date.
Return A zDate object with the current system date.
See also zDate::zDate();
Example // two ways to init objects to current date
zDate date1(zDate::Today());
zDate date2 = zDate::Today();
assert( date1 == date2 );
ZDATE::WEEKOFMONTH
--------------------------------------------------------------------------
Synopsis Returns the week of the month the current day is in.
Syntax int WeekOfMonth() const;
Remarks This routine returns the number of the week the current day
is in. Weeks start from 1 each month.
Return The week number.
See also zDate::WeekOfYear(); zDate::WeeksInYear();
Example // October 17, 1996 is in the 3rd week of October
assert(3 == zDate(zDate::oct,17,1996).WeekOfMonth());
ZDATE::WEEKOFYEAR
--------------------------------------------------------------------------
Synopsis Returns the week of the year the current date is in.
Syntax int WeekOfYear() const;
Remarks This routine returns the number of the week the current date
is in. Weeks start from 1 at the beginning of the year.
Return The week number.
See also zDate::WeekOfMonth(); zDate::WeeksInYear();
Example // October 11, 1996 is in the 41st week of the year
zDate date(zDate::oct, 11, 1996);
assert( 41 == date.WeekOfYear() );
ZDATE::WEEKSINYEAR
--------------------------------------------------------------------------
Synopsis Returns the number of weeks in the year.
Syntax int WeeksInYear() const;
static int WeeksInYear(int aYear);
Remarks This routine returns the number of weeks for a particular
year. The first version uses the current object's year, while
the second one works for any year (of course, the year must
be greater than 1 A.D., as usual). Note that this routine
simply calculates the number of week that December 31 for the
specified year falls in. This may or may not mean that there
were that many weeks exactly.
Return The number of weeks.
See also zDate::WeekOfYear(); zDate::WeekOfMonth();
Example // 1996 has 53 weeks in it
assert( 53 == zDate::WeeksInYear(1996) );
ZDATE::YEAR
--------------------------------------------------------------------------
Synopsis Returns the year of the current object.
Syntax int Year() const;
Remarks This routine returns the year of the current date object.
Valid years start with 1 A.D. The return value is the 4-digit
full representation of the year (that is, for 1996, this
routine will return 1996, and not just 96).
Return The year.
See also zDate::Day(); zDate::Month();
Example zDate date(zDate::oct, 14, 1996);
assert( 1996 == date.Year() );
ZDATE::REFORMMONTH, ZDATE::REFORMYEAR, ZDATE::REFORMDAYNUMBER
--------------------------------------------------------------------------
Synopsis Month, year and day of Pope Gregor's XIII calendar reform.
Syntax static const int ReformYear;
static const month ReformMonth;
static const ulong ReformDayNumber;
Remarks These publicly accessible constants reflect the year (1582),
the month (October), and the day number (577737L, by
convention) of the calendar reform instituted by Pope Gregor
XIII. This happened on October 4, 1582 when the pope canceled
10 days of this month, so the next day became October 15
instead of October 5. This was done because it was discovered
that the Julian calendar used up to this point incorrectly
divided the year in 365.25 days. By 1582, the error was so
big that the church had problems with the Easter and
Christmas which fell during some weird seasons. The pope also
changed the method of calculation of leap years. Before him,
a leap year was every year divisible by 4. The pope decreed
that from then on, a leap year is every year divisible 4
except those divisible by 100 but including those divisible
by 400). We are still using the Gregorian calendar today.
Return n/a
See also zDate::IsLeapYear(); zDate::DayNumber();
Example n/a
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
October 26, 1996
San Angelo, TX
Branislav L. Slantchev
Silicon Creations, Inc.